home *** CD-ROM | disk | FTP | other *** search
/ Mission 3 / Mission 3.zip / Mission 3.iso / demovers / cab_20d / doc / prog / modul.txt < prev    next >
Text File  |  1998-10-29  |  17KB  |  408 lines
  1.  
  2. Kurze Beschreibung der Modulschnittstelle für CAB.APP (bzw. HTML.APP).
  3. ----------------------------------------------------------------------
  4.  
  5. Kontakt
  6. -------
  7. Alexander Clauss
  8. Stresemannstr. 44
  9. D-64297 Darmstadt      email: aclauss@rbg.informatik.th-darmstadt.de
  10.  
  11.  
  12. Hinweise
  13. --------
  14. Das Programm CAB.APP besitzt keine Routinen um online auf das Internet
  15. (bzw. das WWW) zuzugreifen. Der Grund ist: ich habe kein Modem und könnte
  16. diese Routinen deshalb auch nicht testen. Über ein externes Modul
  17. (CAB.OVL) können diese Routinen aber nachgerüstet werden.
  18.  
  19. Die Schnittstelle soll auch unter Single-TOS funktionieren, daher werden
  20. keine speziellen Mint-Features verwendet. Sollte sie für bestimmte Module
  21. unbrauchbar sein, bitte ich um Nachricht.
  22.  
  23. Die Schnittstelle kann an einigen Stellen noch erweitert und verbessert
  24. werden. Sie enthält wahrscheinlich auch ein paar überflüssige Aufrufe, die
  25. zwar in irgendwelchen Alpha-Version eines Moduls benutzt wurden, aber
  26. jetzt höchst wahrscheinlich niemand mehr benutzen wird (z.B. begin_pexec(),
  27. end_pexec() wurden benötigt, weil für die ersten Versuche ein ZMODEM
  28. Programm gestartet wurde, um Daten zu übertragen).
  29.  
  30. Vorschläge zur Verbesserung bzw. Erweiterung der Modul-Schnittstelle werden
  31. gerne entgegengenommen.
  32.  
  33.  
  34. Aufruf des Moduls
  35. -----------------
  36. Es gibt (zur Zeit) zwei Möglichkeiten:
  37.  
  38. 1) CAB.APP läd das Modul CAB.OVL mit pexec(3,...). Das Modul wird dadurch
  39.    in den Speicher geladen und reloziert, aber nicht gestartet. Nun sucht
  40.    CAB.APP nach einer 'magic number' im Speicherbereich des Moduls. Direkt
  41.    hinter dieser Zahl erwartet es die Adresse der Initialisierungs-Routine
  42.    des Moduls. Nun springt es diese Funktion an und übergibt die Adressen
  43.    zweier Strukturen. Eine dieser Strukturen enthält Funktionen, die
  44.    CAB.APP zur Verfügung stellt, und die vom Modul verwendet werden können.
  45.    Die andere Struktur muß von der Initialisierungs-Funktion des Moduls
  46.    ausgefüllt werden, diese muß dort die Adressen der Modul-Funktionen
  47.    eintragen damit sie von CAB.APP aufgerufen werden können.
  48.  
  49.    Die 'magic number' ist:
  50.         0x48744d6c, 0x2f577757, 0x2d42724f, 0x77536552
  51.    CAP.APP gibt dabei nach dem Laden des Moduls mit mshrink() den vom
  52.    Modul nicht benötigten Speicher frei.
  53.  
  54.    Muss das Modul diesen mshrink() Aufruf selbst durchführen, dann muß die
  55.    'magic number' flgendermaßen lauten:
  56.         0x48744d6c, 0x2f577757, 0x2d42724f, 0x77536572
  57.  
  58.    Nachteil dieser Methode: Der Startupcode des Moduls wird nicht
  59.        ausgeführt (und deshalb sind alle Aufrufe von Funktionen die im
  60.        Startupcode initialisiert werden, nicht möglich (betrifft z.B.
  61.        printf()).
  62.  
  63. 2) Als Alternative ist es auch möglich, daß ein Programm, welches die
  64.    Funktionen des Moduls bereitstellt, CAB.APP selbst nachstartet. In
  65.    diesem Fall muß CAB.APP mit dem Parameter -initfunc=<adresse> in der
  66.    Kommandozeile aufgerufen werden. <adresse> steht dabei für die Adresse
  67.    der init-Funktion (in dezimaler Darstellung, also nicht(!) Hexadezimal).
  68.    Die 'Magic Number' wird in diesem Falle nicht benötigt.
  69.  
  70.    Unter Mint mit Memory-Protection muß man dann die Memory-Flags auf
  71.    GLOBAL setzen (bei beiden Programmen), da beide Programme Routinen des
  72.    jeweils anderen aufrufen.
  73.  
  74.  
  75. Aufrufkonventionen
  76. ------------------
  77. Alle Funktionsparameter müssen auf dem Stack übergeben werden. Das
  78. Ergebnis wird im Register D0 übergeben. Variablem vom Typ 'long' sind 32
  79. Bit breit, vom Typ 'int' 16 Bit. Bit 0 bezeichnet das niederwertigste Bit
  80.  
  81. Das bedeutet für Pure C: Alle Funktionen mit 'cdecl' deklarieren
  82. Das bedeutet für den gcc: Die Option '-mshort' verwenden.
  83.  
  84.  
  85. Beschreibung der Funktionen des Moduls
  86. --------------------------------------
  87. In 'modul.h' und 'init.c' (zusammengestellt von Stephane Boisson) befindet
  88. sich schon ein Grundgerüst eines Moduls. Für Aufrufmethode 1) muß man
  89. in main() (welches nie ausgeführt wird) einige Dummy-Aufrufe machen, damit
  90. der Compiler nicht alle Funktionen wegoptimiert.
  91.  
  92.  
  93. long init_module(url_methods_t *out, browser_info_t *in, char *path);
  94. ---------------------------------------------------------------------
  95. Diese Funktion ruft CAB.APP direkt nach dem Start auf. In dieser Funktion
  96. muß sich das Modul initialisieren.
  97.  
  98.    'path'   enthält den Pfad in dem sich das Modul befindet
  99.             (abgeschlossen durch '\').
  100.    'in'     enthält alle Funktionen, die CAB-APP dem Modul zur
  101.             Verfügung stellt.
  102.    'out'    In diese Struktur müssen die Adressen der Modul-
  103.             Funktionen eingetragen werden. Für Funktionen, die
  104.             nicht implementiert sind, setzt man 0L als Adresse
  105.             ein.
  106.  
  107. Als Ergebnis muß die Funktion einen Bitvektor (long) zurückliefern, indem
  108. die vom Modul unterstützten WWW-Protokolle eingetragen wurden.
  109.  
  110. Konstanten für die Protokolle (mit 'Oder' zu veknüpfen):
  111.    SUPPORT_HTTP, SUPPORT_FTP, SUPPORT_GOPHER, SUPPORT_WAIS,
  112.    SUPPORT_MAILTO, SUPPORT_NNTP, SUPPORT_TELNET
  113.  
  114. Falls das Modul weitere Programme mit pexec(0) startet, muß man zusätzlich
  115. noch folgendes in den Bitvektor eintragen:
  116.    SUPPORT_PEXEC
  117.  
  118. Falls die Initialisierung nicht klappt muß 0L zurück geliefert werden;
  119. weitere Aufrufe von Modul-Funktionen finden dann nicht mehr statt.
  120.  
  121. Wichtig für Aufrufmethode 1 (siehe oben):
  122. Die Adresse dieser Funktion muß direkt hinter der 'Magic number' irgendwo
  123. im Programm- oder Datenbereich untergebracht werden, damit CAB.APP diese
  124. Funktion findet und aufrufen kann (gilt nur wenn das Modul mit pexec(3)
  125. von CAB.APP geladen wurde).
  126.  
  127. Wichtig für Aufrufmethode 2 (siehe oben):
  128. Das Modul wird als Programm gestartet, und startet dann selbst CAB.APP,
  129. wobei es die Adresse dieser Funktion als Parameter übergibt:
  130.  
  131.    Parameter:  -initfunc=<adresse>
  132.  
  133.  
  134. void restore_module(void);
  135. --------------------------
  136. Wird aufgerufen, bevor sich CAB.APP beendet. Die Funktion sollte hier allen
  137. angeforderten Speicher freigeben, geöffnete Datein schliessen, etc.
  138.  
  139. Diese Funktion muß nicht implementiert werden, wenn nichts dauerhaft
  140. reserviert wurde (Dateihandles, Speicher, etc.)
  141.  
  142.  
  143. void get_version(char **authorp, long *versionp, long *datep);
  144. --------------------------------------------------------------
  145. Erfragt Informationen über Autor, Version und Datum des Moduls. Alle
  146. Angaben werden im 'About...' Dialog von CAB.APP angezeigt.
  147.  
  148.    'authorp'   Autor und Kontaktadresse. Maximal 4 Zeilen zu je 30 Zeichen.
  149.                Als Zeilentrenner bitte '|' verwenden.
  150.    'versionp'  Version im BCD-Format. Oberes Wort enthält die Haupt-
  151.                versionsnummer, das untere Wort die Unterversionsnummer.
  152.    'datep'     Datum im BCD-Format: 0xYYYYMMDD (Jahr, Monat, Tag)
  153.  
  154. Diese Funktion muß nicht implementiert werden.
  155.  
  156.  
  157. long get_url_info(char *url, long *timep, long *sizep, char *type);
  158. -------------------------------------------------------------------
  159. Über das Dokument mit der URL-Adresse 'url' sollen einige Informationen
  160. ermittelt werden. Diese Funktion wird aufgerufen um zu entscheiden, ob ein
  161. Dokument überhaupt aus dem Internet angefordert werden muß, oder ob das
  162. Dokument im Cache noch aktuell ist.
  163.  
  164.    'url'    URL-Adresse des Dokuments, über das Informationen gefordert
  165.             werden.
  166.    'timep'  Hier muß das Datum (letzte Modifikation) eingetragen werden.
  167.             Im UNIX-Format: Sekunden seit 1970 (01.01.1970,00:00 => *timep=0)
  168.    'sizep'  Hier soll die Länge (in bytes) des Dokuments eingetragen werden.
  169.             -1L wenn nicht feststellbar.
  170.    'type'   Der Dateityp im MIME-Format. Der String-Puffer bietet Platz für
  171.             250 Zeichen. Oder Leerstring '\0', falls unbekannt.
  172.  
  173. Als Ergebnis leifert die Funktion 0, wenn alles geklappt hat, sonst eine
  174. GEMDOS, XBIOS, BIOS, Mint bzw. MintNet Fehlernummer.
  175.  
  176. Diese Funktion muß nicht implementiert werden. Ist für optimale Cache-
  177. Verwaltung aber sinnvoll.
  178.  
  179.  
  180. long get_url(char *url, char *filename);
  181. ----------------------------------------
  182. Das Modul soll das Dokument mit der URL-Adresse 'url' aus dem Internet
  183. holen und in der Datei 'filename' speichern. 'filename' enthält schon den
  184. kompletten Zugriffspfad; Verzeichnisse müssen nicht mehr angelegt werden.
  185. Das Dateidatum sollte korrekt auf das Datum der letzten Modifikation des
  186. Dokuments gesetzt werden. Nur so funktioniert die Cache-Verwaltung in
  187. Verbindung mit der 'get_url_info(..)' Funktion.
  188.  
  189. Sollte das Ziel der URL-Adresse ein Verzeichnis sein (z.B. beim ftp, gopher
  190. Protokoll) sollte das Ergebnis als HTML-Datei abgelegt werden (falls das
  191. nicht schon automatisch im HTML-Format ankommt???). Wenn man die
  192. Verzeichniseinträge mit Icons versieht, kann man die folgenden eingebauten
  193. Icons benutzen:
  194.  
  195.    #define BULLET_FOLDER "<img src=\"internal-gopher-menu\">"
  196.    #define BULLET_TEXT "<img src=\"internal-gopher-text\">"
  197.    #define BULLET_IMAGE "<img src=\"internal-gopher-image\">"
  198.    #define BULLET_MOVIE "<img src=\"internal-gopher-movie\">"
  199.    #define BULLET_SOUND "<img src=\"internal-gopher-sound\">"
  200.    #define BULLET_INDEX "<img src=\"internal-gopher-index\">"
  201.    #define BULLET_BINARY "<img src=\"internal-gopher-binary\">"
  202.    #define BULLET_UNKNOW "<img src=\"internal-gopher-unknown\">"
  203.  
  204. Als Ergebnis leifert die Funktion 0, wenn alles geklappt hat, sonst eine
  205. GEMDOS, XBIOS, BIOS, Mint bzw. MintNet Fehlernummer.
  206.  
  207. Wird die URL-Adresse umgeleitet (Image-Maps,...) muss man dies CAB.APP
  208. mit der Funktion  'new_url' (siehe unten) mitteilen.
  209.  
  210.  
  211. long post(char *url,char *content, char *enctype, char *filename);
  212. ------------------------------------------------------------------
  213. Die Daten ('content') einer FORM-Umgebung werden mit 'POST' an 'url'
  214. geschickt. Die Daten liegen im 'enctype' (MIME) Format vor. Zur Zeit ist
  215. nur 'application/x-www-form-urlencoded' möglich.
  216. Eventuell zurückgeschickte Daten sollen in 'filename' gespeichert werden.
  217.  
  218. Sollten die zurückgeschickten Datein eine neue URL-Adresse besitzen, dann
  219. unbedingt die Funktion 'new_url' (siehe unten) benutzen.
  220.  
  221.  
  222. long mailto(char *url, char *subject, char *filename);
  223. ------------------------------------------------------
  224. Die Datei 'filename' soll als Mail verschickt werden. 'url' bezeichnet
  225. die Email-Adresse des Empfängers als URL, 'subject' ist der Betreff.
  226. Als Ergebnis liefert die Funtkion 0, falls alles geklappt hat, sonst -1.
  227.  
  228.  
  229.  
  230.  
  231. Funktionen, die CAB.APP anbietet (browser_info_t Struktur)
  232. ----------------------------------------------------------
  233. Das Modul kann direkt AES-Aufrufe machen, im Allgemeinen ist das aber nicht
  234. nötig.
  235.  
  236. void (*aes_crystal)(void)
  237. -------------------------
  238. Für AES-Aufrufe bitte die folgenden Arrays ausfüllen und dann 'aes_crystal'
  239. aufrufen.
  240.  
  241.   int *aes_control;
  242.   int *aes_global;
  243.   int *aes_intin;
  244.   int *aes_intout;
  245.   long *aes_addrin;
  246.   long *aes_addrout;
  247.  
  248. void (*aes_messages)(int *msg)
  249. ------------------------------
  250. Besitzt das Modul eine eigene AES-Event-Behandlung, sollte bei jedem
  251. MU_MESAG-Event (bzw. jedem Event, welches nicht das Modul betrifft) der
  252. Ereignis-Puffer mit dieser Funktion an CAB.APP weitergereicht werden, damit
  253. dieses z.B. Redraws ausführen kann.
  254.  
  255.  
  256.  
  257. void (*msg_error)(long errno)
  258. -----------------------------
  259. Gibt eine Fehlermeldung aus (im Statusfenster von CAB.APP). Erlaubt sind alle
  260. GEMDOS, BIOS und MintNet Fehlernummern.
  261.  
  262.  
  263. void (*msg_status)(long no,long val)
  264. ------------------------------------
  265. Gibt eine der folgenden Statusmeldngen aus:
  266.  
  267.    no=1: 'connecting host',                val unbenutzt
  268.    no=2: 'receive data',                   val=Anzahl der empfangenen Bytes
  269.    no=3: 'waiting for response',           val unbenutzt
  270.    no=4: 'resolving host',                 val unbenutzt
  271.    no=5: 'sending request',                val unbenutzt
  272.    no=6: 'Text formatieren...',            val unbenutzt
  273.    no=7: 'Bild laden...',                  val unbenutzt
  274.    no=8: 'Starte Programm...',             val unbenutzt
  275.    no=9: 'Formatiere Tabelle...',          val unbenutzt
  276.    no=10: 'Warte auf Daten (Timeout: #)',  val=Timeout
  277.    no=11: 'Konvertiere Bild...',           val unbenutzt
  278.  
  279. Weitere Meldungen können bei Bedarf aufgenommen werden. Nummern bitte mit
  280. mir absprechen.
  281.  
  282.  
  283. long (*aes_events)(long msec)
  284. -----------------------------
  285. Mit dieser Funktion gibt man CAB.APP die Gelegenheit auf AES-Ereignisse zu
  286. reagieren. CAB.APP ruft evnt_multi(MU_MESAG|MU_TIMER|MU_KEYBD,..) auf,
  287. wobei 'msec' als Zeit für das Timer-Event benutzt wird. Mit einem kleinen
  288. Wert für 'msec' kehrt die Funktion also schnell wieder zurück. CAB.APP ver-
  289. arbeitet zunächst alle eigenen Events (z.B. Redraw, Fenster verschieben,..)
  290. und prüft, ob der Benutzer die Aktion abbrechen will. Als Ergebnis liefert
  291. die Funktion:
  292.  
  293.           0     -> kein MU_MESAG-Event. Weitermachen.
  294.          -1     -> Aktion abbrechen (Benutzer hat ESC gedrückt).
  295.    alles andere -> Pointer auf ein GEM-Message-Array (int msg[8]) mit den
  296.                    Daten des aktuellen MU_MESAG-Ereignises.
  297.  
  298.  
  299. long (*alert_box)(long button,long msg)
  300. ---------------------------------------
  301. Eine Alertbox wird dargestellt. 'button' ist der Default-Button und 'msg'
  302. die Nummer eines Textes. Die Funktion liefert 0, wenn ein Fehler auftrat
  303. (falsche msg Nummer), sonst den ausgewählten Button.
  304. Mögliche Texte (msg):
  305.  
  306.    msg=0 : "[2][Aktion abbrechen?][Ja|Nein]"
  307.    msg=1 : "[1][Transaktion war erfolgreich][Abbruch]"
  308.    msg=2 : "[1][Transaktion war nicht|erfolgreich][Abbruch]"
  309.  
  310. Weitere Texte können bei Bedarf aufgenommen werden. Nummer bitte mit mir
  311. absprechen.
  312.  
  313.  
  314. void (*begin_pexec)(void)    void (*end_pexec)(void)
  315. ----------------------------------------------------
  316. Mit diesen beiden Funktionen muß das Starten eines Programmes durch pexec(0)
  317. geklammert werden. CAB.APP wird sich unter Single-TOS beim AES korrekt ab-
  318. und danach wieder anmelden.
  319.  
  320.  
  321. int (*clear_cache)(long size)
  322. -----------------------------
  323. Sorgt dafür, daß mindestens 'size' Bytes im Cache frei sind. Gegebenenfalls
  324. werden einige Dateien (auf die am längsten nicht mehr zugegriffen wurde)
  325. aus dem Cache entfernt. Konnte soviel Platz geschaffen werden, liefert die
  326. Funktion 0 sonst -1.
  327. size=0 bedeutet, daß der komplette Cache gelöscht wird.
  328.  
  329.  
  330. int (*new_url)(char *url,char **file)
  331. -------------------------------------
  332. Wenn eine Dokument-Anfrage auf eine neue URL-Adresse umgeleitet wird (z.B.
  333. Imagemaps, cgi-Scripts), muß man dies dem Hautprogramm mit dieser Funktion
  334. mitteilen. Es ermittelt dann einen neuen Dateinamen 'file', unter dem die
  335. Daten dann abgespeichert werden müssen. Liefert die Funktion als Ergebnis 0
  336. soll das Dokument jetzt endgültig geholt werden, liefert sie als Ergebnis
  337. -1, dann muß das Dokument nicht mehr geholt werden, da es sich schon im
  338. Cache befindet.
  339.  
  340.  
  341. int (*ask_user)(long msg,char **answer)
  342. ---------------------------------------
  343. Wenn der Benutzter bestimmte Angaben machen muß, bevor fortgefahren werden
  344. kann (z.B. bei geschützten Dokumenten mit Passwortabfrage), kann man diese
  345. Angaben hiermit anfordern.
  346. 'msg' ist die Nummer des Textes, der angezeigt wird, 'answer' ist der
  347. String, der vom Benutzer eingegeben wurde. Das Resultat ist 1 wenn der
  348. Benutzter OK gedrückt hat, 0 für Abbruch und -1 bei einem Fehler (falsche
  349. 'msg'-Nummer). Der String 'answer' wird beim nächsten Aufruf dieser Funktion
  350. wieder überschrieben daher, wenn nötig, umkopieren.
  351. Möglicher Werte für 'msg':
  352.  
  353.    msg=0 : Dokument geschützt, Name (bzw. Kennung) eingeben
  354.    msg=1 : Dokument geschützt, Passwort eingeben
  355.  
  356. Weitere Texte können bei Bedarf definiert werden. Bitte mit mir absprechen.
  357.  
  358.  
  359. long basepage
  360. -------------
  361. Adresse der Modul-Basepage. Nur gültig, wenn Modul mit pexec(3) gestartet
  362. wurde.
  363.  
  364. int *reloadflag
  365. ---------------
  366. Zeiger auf ein integer. Der Integerwert ist 1, wenn der Benutzer 'Neu laden'
  367. (Reload) ausgewählt hat, sonst 0. Kann dazu verwendet werden, eventuell gecachete
  368. Informationen/Daten zu benutzen oder nicht.
  369.  
  370.  
  371. long version
  372. ------------
  373. Versionsnummer von CAB im ASCII format. Beispiel: V1.30 wäre 0x30313330.
  374.  
  375.  
  376. proxy_url *proxy
  377. ----------------
  378. Zeiger auf die folgende Struktur:
  379.  
  380. struct {
  381.    char *ftp_proxy;
  382.    char *http_proxy;
  383.    char *wais_proxy;
  384.    char *gopher_proxy;
  385.    char *news_proxy;
  386.    char *no_proxy;
  387.    char *smtp_server;
  388.    char *nntp_server;
  389. } proxy_url
  390.  
  391. Das OVL sollte diese Struktur innerhalb der init-Funktion mit
  392. Default-Werten ausfuellen. CAB hat fuer jeden String schon Speicher
  393. (126 Bytes) reserviert. CAB wird diese Einträge ändern, falls der
  394. Benutzter neue Einträge in CAB bestimmt. Das OVL sollte deshalb
  395. vor dem Download der Daten diese Einträge benutzten.
  396.  
  397.  
  398. void online(int state)
  399. ----------------------
  400. Sollte vom OVL immer dann aufgerufen werden, wenn die Internet-
  401. verbindung aufgebaut bzw. abgebrochen wird. Besteht die Verbindung
  402. muß state=1 sonst state=0 übergeben werden. Diese Funktion darf
  403. ab CAB-Version 1.41 aufgerufen werden (d.h.: version>=0x30313431).
  404. Wird diese Funktion vom OVL nicht aufgerufen, geht CAB davon aus,
  405. daß die Internetverbindung besteht.
  406.  
  407.  
  408.